\input texinfo  @c -*-texinfo-*-
@c *******************************************************
@c * Documentation for MX2 - Multitasking Kernel         *
@c * This documentation was converted to TeX using the   *
@c * GNU documentation macros ver 1.13 by Brian Holmes:  *
@c *           BITNET: BHOLMES@WAYNEST1                  *
@c *         Internet: Brian_Holmes@um.cc.umich.edu      *
@c *******************************************************
@settitle MX2 Multitasking Kernel
@synindex tp vr
@titlepage
@sp 10
@center @titlefont{MX2 Multitasking Kernel}
@center for Atari ST computers
@sp 3
@center by
@sp 3
@center @titlefont{Fred Brooks}
@end titlepage
 
@chapter Introduction
@bullet Due to my now being a multimillionaire I am forever giving away
the complete source and the complete program is now:
@example
                  !!!       PUBLIC DOMAIN     !!!
 
                  !!!          FREE           !!!
@end example
@bullet        As a service to help down and out C programmers around the
       world you can still send a donation to:
@example
               Fred Brooks
               4145 44ST #5
               San Diego CA 92105
@end example
@bullet                You will receive a thank you and can continue
to live with a clear conscience.
@br
@bullet MX2 V2.3.0    A multitasking and multiuser
environment for ATARI ST.
Written using TDI Modula-2 3.01a Compiler
For TOS Versions 11/20 1985 and 04/22 1987
Other Versions may not run correctly.
@br
@bullet This set of programs are NOT for sale by anyone and I
reserve all rights to it's ownership.
@br
MX2 is a multitasking environment to aid in program development
for the ATARI ST. It was developed in Modula-2 but can be used
with any language such as C, BASIC, or PASCAL. Suggested system
minimum requirements are 1 MEG of memory with a double-sided
disk drive. A hard disk drive will greatly improve system
performance.
 
@chapter Notes:
       I have tuned this kernel for use with the GULAM shell. I have
       had no problems using it except with the TE communications
       command. It locks up my background xmodem routines if used.
 
 
@chapter System Generation:
 
       The MX2.INF file contains the system generation parameters.
       It is an ASCII files that can be edited with the UE editor in
       GULAM or any ASCII editor This files allows you to change the
       default system boot parameters
       If this file does not exist the default values are:
               numeric values are in decimal
 
 @example
       Init Command              : IP CLI.PRG
       System Memory             : 32000
       Alt Program HOTKEY        : 3276800
       Normal Mouse HOTKEY       : 3211264
       Cursor Mouse HOTKEY       : 3014656
       Reboot HOTKEY             : 1245184
       Reserved Memory           : 32000
 @end example
       The initialization command is normally used to load the SHELL
       program. The CLI.PRG enables GULAM.PRG to multitask then loads
       the program. If the program is exited the kernel will respawn
       the SHELL. To load a program other than the SHELL edit the line to
       to IP "name of program".
 
       System memory is the size of the memory reserved by MX2 to
       allocate for it's internal data structures. The default size
       should be adequate for 7 MX2 processes with a workspace of 2K
       each.
 
       Reserved memory is the size of the memory block that will be split
       off of the main memory heap.  This memory should still be available
       with GEM programs that allocate all available memory with a malloc(-1).
 
@chapter MX2.ACC:
 
The MX2.ACC will not work correctly if you try to run two or more GULAM
shells. Because both would be GEM programs and the AES would hang or get lost
. If you want to have a remote or wish to run two shells from the desk to
please select the OFF option from the desk ACC before starting up the second
shell with the go.g script file or by typing the commands. I am trying to
work around this problem.
 
@chapter LOGIN and PASSWD file:
 
@bullet The MX2 password system uses five fields separated by a colon.
@bullet The file 'passwd' contains all password records.
 
@itemize
@item
field 1        userid
@item
field 2        password
@item
field 3        path
@item
field 4        program
@item
field 5        comment
@end itemize
 
@example
Example        mx2::::
@end example
 
Is the minimum password record. It contains only the userid field with the
other fields set to null. This would login user 'mx2' with no password to
the default path 'current path' and run the default program 'gulam.prg'.
@example
Example        fred:AXKHRWQ:c\mx2:gulam.prg: login as me using my work id
@end example
Would login user 'fred' using encrypted password 'AXKHRWQ' to drive 'c'
path '/mx2' "note if a drive is specified DO NOT use a colon between the drive
character and the path" and run program 'gulam.prg'. The comment is not used
by the program and is there to inform the user. The program field could have
been a null entry or any other valid program. The program field
may include subdirectories. ie ':\mx2\gulam.prg:'
 
The 'passwd.prg' is used to set and change user passwords. New users must
have a null field 2 when it is created. Passwords MUST be set with the
passwd.prg.
@example
USAGE:          passwd fred
                        ^
                       user
@end example
Where fred is a system username in field 1 of a password record.
If there is no password the program will ask for a new password.
If a password already exists you will be asked for the old password
first, then if it is correct you can change the password. Passwords must be
at least 4 characters long.
 
Examine the supplied passwd file for more examples.
 
@chapter Interface Libraries:
 
       The SYSCALL module is the standard interface for user programs
       to the MX2 Multitasking system. It includes functions to starting
       ending and controlling concurrent processes. The TDILIB contains
       the TDI MODULA-2 3.01a libraries. I will include a portable C
       library as soon as I can translate the code over.
 
@chapter Communications:
 
       Also included is a no frills communications program.
       COM.TOS without options sets the AUX port to 1200BPS.
       COM.TOS # "where # is a number" will set the AUX port to
       the speed according to the table.
@example
              0      =    300BPS
              1      =    1200BPS
              2      =    2400BPS
              4      =    4800BPS
              9      =    9600BPS
              H      =    19200BPS
@end example
       Use the [Undo] key to exit back to the CLI.
 
@chapter MX2 Hotkeys:
 
       Hotkeys for several functions are included. These are the default
       keys they can be changed in the MX2.INF file.
@table @code
@item ALT m
Load and switch to second CLI or program, the screen and status
of the first cli are saved. If used after the second
CLI was loaded this command will switch back and
forth between the two. It is recommended that this
command only be used in TOS programs. If a you only press
RETURN after the program name prompt the CLI.PRG will
automatically be loaded.
@item ALT r
Will REBOOT the computer. This is the same as pressing the
reset button on the ST.
@end table
@chapter Background Timer:
       @code{CRON} is the background program timer. When MX2 starts the file
       @code{CRONTAB} is read into memory. CRONTAB lists the start time and
       frequency of the MX2 command on that line to be executed. To
       stop the @code{CRON} from running the entries in the @code{CRONTAB} file
you
       can rename it or after the CLI is running issue the "SYS CRON OFF"
       command to stop.
 
       All times are in minutes. You may have up to 16 entries in the
       CRONTAB file. The format of the CRONTAB file is.
@example
       Start Time      Frequency       Command
       0               60              SYS BP DUMMY.PRG
@end example
       midnight        every hour      run the DUMMY.PRG in background
@chapter NETWORKING:
@table @samp
@item netaux.prg
networking program that uses the aux port.
@item netmidi.prg
networking program that uses the midi port.
@item neta.g
Gulam script file to start the netaux.prg in background.
@item netm.g
Gulam script file to start the netmidi.prg in background.
@end table
 
       The network uses the MIDI or AUX port to allow a second ST that
       is also running MX2 to use the remote ST's drives. The remote
       drives can be used just like your local drives but they will of
       course be slower because of the transfer of the data through the
       MIDI or AUX ports. The remote drives will start as the second drive ID
       after the last drive that you have on the local ST. For example
       if you have drives A,B,C,D,E,F then the remote drives will be
       H,I,J,K,L,M respectively.        To use the C drive on the remote
       system simply use the J: drive on the CLI. Be sure to cross connect
       the midi cables ie... the MIDI out to the MIDI in on the other ST
       and vice verse.
@example
                           midi in ___  ___ midi in
                 ST 1                 \/                 ST 2
                          midi out ___/\___ midi out
@end example
 
       If the AUX port is selected for the network a NULL modem
       cable should  be used for direct connect or a normal
       modem cable for use through remote lines. The BAUD rate
       can be set by the CLI or a DESK ACC.
 
       The MX2NET.PRG is a standalone network driver that runs from
       the DESKTOP or another GEM program. It may be installed in an
       AUTO folder or run from the DESKTOP. It will allow disk sharing
       between ST's that are not both using the MX2 environment.
 
@chapter MISC:
 
       The condition of the CapsLock is shown by an asterisk in
       the upper right corner.
 
@chapter Known Bugs, Fixes and Improvements:
@itemize @bullet
@item
       V1.1.0  Process priorities are now fixed.
@item
       V1.0.0  The spooler will not work with networked files.
@item
       V1.0.0  MX2.ACC accessory will allow MX2 to multitask in some GEM
               programs. The TDI editor will allow MX2 to switch when running
               this accessory.
@item
       V1.1.0  Improved the MX2.ACC to multitask with more gem programs.
               I have used a vector to read the Super stack of the ACC
               and passed it to the scheduler to help it know when it's
               safe to context switch.
@item
       V2.1.0  Added code so the MX2.ACC does not soak up cpu time until
               MX2 has started. The desk accessory check every 10 seconds
               for the MX2 running flag then it starts a zero time event
               timer call.
@item
       V1.0.0  Some programs will start up ok but on exit cause the system to
               crash.
@item
       V2.0.0  I hope I have solved this problem. Most programs should run
               correctly now without problems. Some programs won't run with
               the GULAM shell even without MX2.
@item
       V1.0.2  Added KILL command to terminate processes and their
               children. This command will not work with programs
               run as background processes.
@item
       V1.1.0  Added support for use of AUX port for network along
               with MIDI.
@item
       V1.1.0  Added I/O options for selecting ports on background
               programs. Example a 'sys bp -a -p cli.prg' would start
               command shell that uses the aux port for input and uses
               the printer port for output. You could send input from
               the main CLI by using the 'submita.prg'
               Example: 'submita ls' would send the the ls command into
               the aux buffer which the cli would read and send the
               directory output to the printer.
@item
       V1.1.0  Changed usage of reserved memory.
@item
       V2.2.0  Fix bug in PS command that displayed incorrect start time
               and date for processes.
@item
       V2.2.1  Remove PS command code from kernel. All code is now is the PS
               Program.
@item
       V2.3.0  I have deleted the trap 15 interface because of problems
               with a few programs. There is now a vector to all the MX2
               system routines.
@item
       V2.3.0  Added user device drivers. When a background program is
               started one of the drivers in the range of 0 to 3 may be
               selected. The device driver routines types are defined in
               the ATOMIC.DEF file. All bios calls to the keyboard and
               screen will be redirected the these routines. Of course
               user will have to load the address of his routines into
               the correct entry in the DeviceTable. A call to get the
               system variables will allow you to get the correct address
               of the DeviceTable. Look at the file device.mod for an
               example to how to load and use the device drivers.
@end itemize
 
@chapter MX2 Commands:
               () mandatory parameter, [ ] optional parameter
               priorities range from 1 to 10 where 10 gets the
               most CPU time.  Always use SYS before
               all commands if run from the CLI.
 
@chapter Program Commands:
@table @code
@item IP
Run Interactive Program. This is normally only used to
                 run the mx2 CLI when the kernel first boots. The kernel
                 will respawn the program if it terminates or exits.
@example
USAGE : IP [priority] (filename) [command]
        SYS IP [priority] (filename) [command]
@end example
@item BP
Run Background Program.
                 Background programs use the same I/O vectors as the process
                 that started it.
@end table
@example
USAGE : BP [-pacmn0123] [-pacmn0123] [priority] (filename) [command]
        SYS BP [-pacmn0123] [-pacmn0123] [priority] (filename) [command]
@end example
                         The -pacmn0123 argument allows for controlling the port
                         that the program STDIO will use for INPUT and OUTPUT.
                         The first argument is for INPUT, the second for OUTPUT.
                         parameters are:
@example
  p : printer port
  a : rs232 port
  c : console 'keyboard or screen'
  m : midi port
  n : null device
0-3 : userdefinable I/O drivers
@end example
                         The NULL device always returns a ready status for
                         input and output. If the port options are missing
                         CON I/O will use the console and screen.
@example
Example:    'sys bp -a -p doit.prg' will cause the doit program
             to use the rs232 port for INPUT and will print
             OUTPUT through the printer port.
@end example
@page
@table @code
@item FP
Run Foreground Program.
                 Foreground programs always use the normal ST I/O vectors.
                 Use it to run programs that use the ST screen and
                 keyboard from processes that are redirected to the
                 RS232 or other ports.
@end table
@example
USAGE : FP [-pacmn0123] [-pacmn0123] [priority] (filename) [command],
        SYS FP [-pacmn0123] [-pacmn0123] [priority] (filename) [command]
@end example
                         The -pacmn0123 argument allows for controlling the port
                         that the program STDIO will use for INPUT and OUTPUT.
                         The first argument is for INPUT, the second for OUTPUT.
                         parameters are:
@example
  p : printer port
  a : rs232 port
  c : console 'keyboard or screen'
  m : midi port
  n : null device
0-3 : userdefinable I/O drivers
@end example
                         The NULL device always returns a ready status for
                         input and output. If the port options are missing
                         CON I/O will use the console and screen.
@example
Example:    'sys fp -a -a cli.prg' will cause the cli program
             to use the rs232 port for INPUT and OUTPUT.
@end example
@table @code
@item PORT
Select stdio ports.
@end table
@example
USAGE : PORT (pid) [-pacmn0123] [-pacmn0123]
        SYS PORT (pid) [-pacmn0123] [-pacmn0123]
@end example
                         The -pacmn0123 argument allows for controlling the port
                         that the process STDIO will use. This command will not
                         affect the main CLI.
@chapter XMODEM Commands:
@table @code
@item XR
Receive a XMODEM file from remote computer.
@example
                 USAGE : XR ([-]filename)
@end example
                       This command will start a background process to
                       download a file. If the download is complete a single
                       bell will sound at the console. If the download
                       aborted for some reason four bells will sound.
                       Transfers default to CRC, a - in front of the filename
                       will cause a switch to checksum error-checking.
@item XT
Send a XMODEM file to a remote computer.
@example
                 USAGE : XT ([-]filename)
@end example
                       This command will start a background process to
                       upload a file. If the upload is complete a single
                       bell will sound at the console. If the upload
                       aborted for some reason four bells will sound.
                       Transfers default to CRC, a - in front of the filename
                       will cause a switch to checksum error-checking.
@item XA
Abort XMODEM transfers.
@example
                 USAGE : XA
@end example
                       This command will abort all xmodem background
                       processes.
@item XS
XMODEM Status.
@example
                 USAGE : XS
@end example
                       This command will display the status of a
                       xmodem up or download.
@end table
 
@chapter Process Priority:
 
       NICE    : Change Process Priority.
@example
           USAGE : NICE (priority) [pid], SYS NICE (priority) [pid]
@end example
                       If NICE is called without a pid the current process
                       will be used.
 
@chapter PROCESS COMMANDS:
@table @code
@item HP
Halt Process.
@example
                 USAGE : HP (pid), SYS HP (pid)
@end example
                       Pid is the process id number of the process you
                       wish to Halt. To start up a halted process use
                       the WP command. The HP command takes a process out
                       of the ready list and removes it from the CPU but
                       NOT from memory.
@item WP
Wakeup Process.
@example
                 USAGE : WP (pid), SYS WP (pid)
@end example
                       Pid is the process id number of the halted process
                       you wish to Wakeup. The WP command puts the process
                       back into the ready list to be run in it's time
                       slot.
@item KILL
KILL Process.
@example
                 USAGE : KILL (pid), SYS KILL (pid)
@end example
                       Pid is the process id number of the process you
                       wish to terminate. The KILL command removes the process
                       from the ready list and releases it's workspace back to
                       the system process memory.
@end table
 
@chapter Background Timer Commands:
@table @code
@item CRON
Background Scheduler Timer.
@example
                 USAGE : SYS CRON [ON OFF]
@end example
                       CRON with no options will display the current
                       timer table entries. CRON OFF disables the timer.
                       CRON ON read the CRONTAB file, reloads the timer
                       table then enables the timer.
@end table
 
@chapter MX2 Utility Programs:
 
@section Process Status Commands:
@table @code
@item PS.PRG
Process Status.
@example
                 USAGE : PS
@end example
                       Display description of all system processes.
@item PS.PRG -z
Zombie Process Status.
@example
                 USAGE : PS -z
@end example
                       Display description of all inactive system
                       processes.
@item PID.PRG
Process Identifier.
@example
                 USAGE : PID
@end example
                       Returns the Process Identifier of the current
                       process.
@item REDIR.PRG
Program to redirect screen and keyboard I/O to
                       the RS232 port.
@item COM.PRG
Program to communicate thru the RS232.
@item SUBMIT.PRG [cmd]
Program to send string on the command line to the
                       keyboard buffer.
@example
      SUBMITA.PRG [cmd] send string to RS232 buffer.
      SUBMITM.PRG [cmd] send string to MIDI buffer.
@end example
@item MX2.ACC
Desk accessory to allow MX2 to multitask in
                       some GEM programs. You can disable GEM Multitasking
                       if you click on the Desk menu bar for MX2 and select
                       the OFF button.
@end table
@section SYS.PRG  Usage:
 
       The SYS.PRG reads it's command line and submits the command the
       the MX2 kernel. It's use to give MX2 commands from another
       program such at GULAM. Example "SYS BP LOOP.PRG" will load
       and run LOOP.PRG as a background process. All MX2 commands
       can be used. To get a process status enter "SYS PS"
 
@chapter Useful Script Files:
@table @code
@item  startlp.g
Gulam script file to start the background spooler.
                       This runs the SPOOLER.PRG as a background process.
@item pr.g
This Gulam script file will copy the file(s) on it's
                       command line to the MX2 spool directory than start the
                       SPOOLER.PRG if it has already been run as a background
                       process.
@item go.g
Gulam script file will start a background shell that
                       uses the AUX port for I/O.
@end table
 
@chapter Design and Implementation:
 
       MX2 is not a CLI shell. It provides a platform for system
       services for a CLI or programs. When MX2 boots it looks for
       CLI.PRG in its directory. If it exists it will be run as an
       Interactive Process as the command shell.
 
@chapter Setup:
 
       First create a directory \MX2, Move the MX2VX.X.X archive into this
       directory. Unarchive the main archive. The source.arc and tdilib.arc
       file may be placed into separate directories and unarchived.
       You MUST have a copy of GULAM.PRG for the SHELL. It is included with
       the main archive. Start the MX2.PRG causing the CLI.PRG will load
       and be ready for user login into the system.
 
       I have included a few batch files to set up and to help run a
CLI in background to the RS232 port.
       Please let me know of any fixes that you come up with or
       improvements.
 
       HOME PHONE 619-584-0281 San Diego CA.   5PM-10PM Please.
@c Print table of contents
@contents
@bye
